Now that World Builder has been released to the public domain, I've been flooded with questions from new users. One of the most common questions refers to the syntax of the WB programming language. The "syntax error near the insertion point" dialogue box pops up frequently when these new authors attempt to write scene code. What does it mean, and what can be done about it?
Like any spoken language, WB's programming language has it's own syntax. That is, a set of grammatical rules about how the code must be written. These rules include constraints on spelling, capitalization, punctuation, and the order in which the words appear in each line of code. World Builder's syntax is simple:
• Commands must be typed in capital letters -- TEXT$, CLICK$, PLAYER@, etc.
• Commands must be separated from the other items in statement by braces -- {}
• There can be no space between a command word and a brace -- SOUND{HORN}
• Names of scenes, characters objects and sounds must be spelled exactly the way you named them when you created them.
• Variable names must be in capital letters.
If any of the rules are broken, the syntax is wrong, and the code will not be accepted by the program. Attention to detail is important. For example, the following simple statement:
MOVE{PLAYER@}TO{STORAGE@}
There are numerous ways to make syntax errors in this statement. If a brace is missing, or you used a bracket instead of a brace; if the words are in lower case instead of all caps; if there's a space between one of the command words and a brace -- the statement will be unacceptable.
When there is a syntax error in your code, the program will notify you with the familiar "syntax error" dialogue. The flashing insertion point will be on the line that contains the error, not necessarily on the error itself. So check the statement carefully, looking for anything that is not right.
Here are some examples of correct and incorrect syntax:
Correct:
IF{TABLE.1=SCENE@}THEN
Incorrect:
IF(TABLE.1=SCENE@)THEN *parenthesis instead of braces
IF{TABLE.1=SCENE$}THEN *dollar sign instead of @
IF{TABLE.1=SCENE@ }THEN *space between SCENE@ and the last brace
Here are some more examples:
Correct:
IF{CLICK$=DOOR.CLOSED}THEN
PRINT{The door is locked.}
EXIT
Incorrect:
IF{CLICK@=DOOR.CLOSED}THEN *used @ instead of dollar sign after CLICK
PRINT{The door is locked.}
EXIT
IF{CLICK$=DOOR.CLOSED}THEN
PRINT{The door is locked.}
*statement is missing END or EXIT
IF{CLICK$ = DOOR.CLOSED}THEN *spaces around the equals sign
PRINT{The door is locked.}
EXIT
IF{CLICK$=DOOR.CLOSED}THEN
PRINT {The door is locked.} *space between PRINT and first brace
EXIT
Correct:
LET{A1#=100}
Incorrect:
LET{A1=100} *Pound (number) sign missing from variable name
let{A1#=100} *LET command is in lowercase, not caps
There are some errors that WB can't detect. If you've misspelled the name of a scene, character, object or sound, there is no way that WB catch it. The only way you'll know if you've misspelled the name of something is when the scene code doesn't work the way it's supposed to.
World Builder also will not catch syntax errors in MENU statements. MENU is used to make custom Command menus.
Using MENU:
With the MENU statement, you can configure the Command menu of any scene to your specifications. For most games this is unnecessary. However, there are occasions when you want to provide something other than the usual commands.
When you use the MENU statement, all the usual contents of the Command menu are discarded. If you merely want to add one special command to the standard commands, you will find it necessary to write all of the standard commands into your MENU statement as well.
Each command must be separated by a semicolon. Command-key equivalents for menu commands are done by adding a slash and the appropriate letter after the command, like this: North/N. Remember that the Edit menu uses the letters Z, X, C, V, and B, so don't use them in your Commands menu.
You can add a dividing line to your menu by using a left parenthesis followed by a hyphen: (-}. Dividing lines are commonly used to separate the directional commands from action commands. Notice that the hyphen is also followed by a semicolon:
(Note: this example does not include all the standard commands.)
You can also use different font variations in your menu. There are five styles, and you can use them by adding a < after the command, followed by the initial of the styles you want to use:
MENU{North/N;South/S;Fly<B}
In this case, the command Fly will be displayed in boldface. These are the five styles available, and their initials:
<B Bold
<I Italic
<U Underline
<O Outline
<S Shadow
You can also make the MENU statement conditional, as part of an IF/THEN statement. This is useful when you want to make the Command menu change after the player has done a certain action.
Custom menus should be used sparingly, if at all. And in most cases you should be very careful to include all of the standard commands, plus their command-key equivalents, to maintain consistency and avoid confusing the player.
Conditional (IF/THEN) Statements:
When you want something to happen in the game, but only under certain conditions, then you have to create an IF/THEN statement that checks to see if the condition exists. If the condition the statement is looking for does exist, then the statement is said to be true. If the statement is true, then the actions that follow the IF/THEN part of the statement will be executed. Here is a simple example:
IF{TEXT$=SEARCH}THEN
PRINT{You find nothing of interest.}
EXIT
In this case, the condition you are looking for is the player entering the command, "search." You don't want the text to be printed just any old time, only when the player enters "search." The IF/THEN statement checks to see if this has occurred. If it has, then the PRINT part of the statement is executed. The entire statement must close with either END or EXIT. In this case, I used EXIT, since I don't want anything else to happen after the text has been printed.
"Action" Statement Types:
The PRINT statement is the simplest of World Builder's code statements. It is what I call an "action statement, since it is what you use to cause something to happen in the game, such as displaying a text message.
Anything you put in the braces following PRINT will be displayed in the text window when the PRINT statement is executed. The text will automatically wrap to fit inside the text window. However, it should be noted that WB has problems with exceptionally long sections of text. For this reason, if you have several sentences to print, you should try to break them up into a couple (or more) individual PRINT statements, like this:
PRINT{The trader takes your gold and gives you some information:}
PRINT{TRADER: "I've heard of this ring you seek. The Old Ones say that it was forged by dwarves in the heart of the great Fire Mountain.}
PRINT{"Only the rarest, most magical of metals were used in its construction, imbuing it with great power.}
PRINT{"According to the legends, it can be found beneath the Heart of Stone."}
In this example, if all of the trader's information was part of one PRINT statement, it would be too long, and would be displayed with parts of it missing. Exactly when a section of type is too long, I don't know. But if the text is missing anything when you test the game, you'll know what to do.
Other types of "action" statements are MOVE, SOUND, and LET.
MOVE is used to move Characters or Objects, whether mobile or immobile, to and from STORAGE@, to another scene, or to the player or another Character.
SOUND plays whatever sound it names: SOUND{GUNSHOT}
LET is used to set a variable. Here are some examples:
LET{A1#=10}
LET{PHYS.HIT.CUR#=PHYS.HIT.CUR#-40}
LET{H2#=RANDOM#}
In most cases these statements are used as part of an IF/THEN condtional statement. You can use any of these "action" statements by itself if you need to. However, unless these things are part of an IF/THEN statement, they will be executed every single time the player enters a command or clicks on an object or character. Usually this is useful only when you need to update a variable to keep track of the player's moves, health, etc.
Action statements by themselves do not require any kind of closing word. IF/THEN statements must always be closed, with either END or EXIT.
Nested Statements:
You can "nest" one or more conditional IF/THEN statements inside another one, to test for multiple conditions. When you do this, every IF/THEN statement must close with either END or EXIT. And nested statement who's conditions are not met, is ignored. Here is a simple nested statement example:
IF{TEXT$=SEARCH}THEN
IF{DARK.1=SCENE@}THEN
PRINT{It is too dark to find anything.}
EXIT
PRINT{There is a hole in the ceiling, leading UP into the attic.}
EXIT
In this example, the first statement tests to see if the player has entered "search." If that is true, then the inner statement tests to see if the scene has been blacked out (for instance, if the player needs a flashlight or torch.) An object called "DARK.1" contains a solid black square that covers the entire scene. If "DARK.1" is in the scene, then the inner statement is true, and text is printed telling the player that it is too dark to find anything. This statement closes with EXIT, which stops the program right there. No other action will occur until the next time the player enters a command or clicks on something.
If the "DARK.1" object is NOT in the scene, then the inner statement is false, and is ignored. The rest of the "search" statement can then be printed, which tells the player what he finds when he searches the lighted room. The "search" statement also closes with EXIT in this example, since I don't want anything else to happen after the text is displayed.
